Using the CtlHTML Control Library

Do the following steps to add the CtlHTML Control Library to a program:

Add #include "CtlHtml.h" to StdAfx.h or any file that uses the CtlHTML Control Library.

Add the appropriate CtlHtml.lib file to the project build.

Use CtlHTML.lib for the Standard (shareware) version DLL.
Use CtlHTMLp.lib for the Pro version DLL.
Use CtlHTMLs.lib for the Pro version static link library.
Use CtlHTMLm.lib for the Pro version static link library for MFC.

Create the program's dialog box resources. The CtlHTML Control Library works by subclassing the basic Windows controls (specifically, static text, read-only edit boxes, command buttons, check boxes, radio buttons, group boxes, and icons). This means you use the standard Windows controls in the dialog editor. Add HTML tagging as desired. Note that it is usually easier to set the control size and location before you add the HTML tags since the tagging changes the size of the text.

Call the CtlHTMLSubclassDialog function to subclass the controls in the dialog boxes that use HTML tagging. Note that edit box controls are subclassed only if they are read-only and have HTML text, so you need to assign the edit box control text before calling CtlHTMLSubclassDialog. For example with MFC:


      BOOL CMyDialog::OnInitDialog() 
      {
         CDialog::OnInitDialog();
      
         CWnd *pWnd;

         // Note: Must set edit box text before calling CtlHTMLSubclassDialog, otherwise 
         //       these controls will not be subclassed
         if ((pWnd = GetDlgItem(IDC_EDITBOX)) != 0)
            pWnd->SetWindowText("<HTML>This is HTML text.</HTML>");

         // init HTML controls
         CtlHTMLSubclassDialog(m_hWnd);
         return TRUE;
      }

Call the CtlHTMLSetColors function to set the control colors to the current system colors. This function should be called in response to the WM_SYSCOLORCHANGE message. Note that the library will work fine without handling this message, but the control colors may be wrong if the user changes the Windows color scheme while your program is running. For example with MFC:


      void CMainFrame::OnSysColorChange ()
      {
         CFrameWnd::OnSysColorChange ();
         CtlHTMLSetColors();
      }

Call the HTMLResetFonts function to reset the fonts after a system font change. This function should be called in response to the WM_FONTCHANGE message. Note that the library will work fine without handling this message, but the control fonts may be wrong if the user changes fonts while your program is running. For example with MFC:


      void CMainFrame::OnFontChange ()
      {
         CFrameWnd::OnFontChange ();
         HTMLResetFonts();
      }

Optionally, call the CtlHTMLDialogEnable function to make it obvious when a dialog box is inactive. You can also call the CtlHTMLOptions function to determine if disabled control text should be flat gray or 3-D and if disabled graphics should be dithered to give them a muted appearance. We recommend using the default options. For example with MFC:


      void CMyDialog::OnActivate (UINT nState, CWnd* pWndOther, BOOL bMinimized)
      {
         CDialog::OnActivate(nState, pWndOther, bMinimized);
         CtlHTMLDialogEnable(m_hWnd, nState != WA_INACTIVE);
      }

Optionally, call the HTMLSetFont function to set the typeface and point size for both the CtlHTML controls and message boxes. The default font is 8 point MS Sans Serif. For example with MFC:


      BOOL CMyApp::InitInstance()
      {
         ...
         // init CtlHTML Control Library - set the fonts
         HTMLSetFont(_T("Tahoma"), 8);
         ...
         return TRUE;
      }

If you are using a statically linked version of the library, there are two additional steps. Static link libraries are included in the Pro version only. None of these steps are required for the DLL version. Note that while using a static link library requires extra steps, using one eliminates having to ship a CtlHTML Control Library DLL with your program, thereby eliminating the possibility of configuration-related problems that often arise when using shared DLLs.
First you need to call the InitCtlHtml and ExitCtlHtml functions to initialize and exit the library. Second, you need to include the resources found in \CtlHtmlRes.rc and the resource IDs found in \CtlHtmlRes.h. For example with MFC:


      BOOL CMyApp::InitInstance()
      {
         ...
         // init CtlHTML Control Library - necessary for static link library version
         InitCtlHtml(AfxGetInstanceHandle());
         ...
         return TRUE;
      }

      int CMyApp::ExitInstance() 
      {
         // exit the CtlHTML Control Library - necessary for static link library version
         ExitCtlHtml();
         return CWinApp::ExitInstance();
      }

If you are using the Standard (shareware) version of the CtlHTML Control Library, you should also register the library with Windmill Point Software. By registering, you will be given a procedure to eliminate the annoying Unregistered Version dialog box displayed during initialization. Registration also entitles you to technical support.

That's it. That's all you need to do.

Debugging the CtlHTML Control Library

The following is a list of the most common mistakes made when using the CtlHTML Control Library. If the control library doesn't work as you expect, chances are you have made one of the following mistakes:

If using a static link version of the library, you may have forgot to call the InitCtlHtml function to initialize the CtlHTML Control Library. If you have memory leaks, you may have forgot to call the ExitCtlHtml function.

If you see the HTML tags when you display a dialog box in your program, you may have forgot to call the CtlHTMLSubclassDialog function in the MFC OnInitDialog function or in response to the WM_INIT_DIALOG message to subclass the controls. Alternatively, you may have added tags to a control not support by the library. Note that you will always see the HTML tags when viewing a dialog box with a dialog box editor.

If the HTML text isn't right, you may have made an HTML tagging error. You may have made a typo in a tag, used an unsupported tag or attribute, or forgot the appropriate end tag.